/**
 * @file
 * @brief xwos::autosar::cp::os::spinlock
 * @author
 * + 隐星魂 (Roy Sun) <xwos@xwos.tech>
 * @copyright
 * + Copyright © 2015 xwos.tech, All Rights Reserved.
 * > This Source Code Form is subject to the terms of the Mozilla Public
 * > License, v. 2.0. If a copy of the MPL was not distributed with this
 * > file, You can obtain one at <http://mozilla.org/MPL/2.0/>.
 */

#ifndef __xwos_arcos_spinlock_h__
#define __xwos_arcos_spinlock_h__

/**
 * @defgroup arcos_spinlock xwos::autosar::cp::os::spinlock
 * @ingroup arcos
 *
 * ## Compliances
 *
 * ### Multi-Core
 *
 * + [ ] [SWS_Os_00648] The AUTOSAR Operating System shall provide a spinlock
 *       mechanism that works across cores. (SRS_Os_80018, SRS_Os_80021)
 * + [ ] [SWS_Os_00649] The AUTOSAR Operating System shall provide a `GetSpinlock()`
 *       function which occupies a spinlock. If the spinlock is already occupied,
 *       `GetSpinlock()` shall keep on trying to occupy the spinlock until
 *       it succeeds. (SRS_Os_80018, SRS_Os_80021)
 * + [ ] [SWS_Os_00650] `GetSpinlock()` shall be callable from Task
 *       level. (SRS_Os_80018, SRS_Os_80021)
 * + [ ] [SWS_Os_00651] `GetSpinlock()` shall be callable from Category 2 ISR
 *       level. (SRS_Os_80021)
 *       The behavior of `GetSpinlock()` is undefined if called from a category 1 ISR.
 * + [ ] [SWS_Os_00652] The AUTOSAR Operating System shall provide a
 *       `TryToGetSpinlock()` function which occupies a spinlock. If the spinlock is
 *       already occupied by a Task, `TryToGetSpinlock()` shall
 *       return. (SRS_Os_80018, SRS_Os_80021)
 * + [ ] [SWS_Os_00653] `TryToGetSpinlock()` shall be callable from Task
 *       level. (SRS_Os_80018, SRS_Os_80021)
 * + [ ] [SWS_Os_00654] `TryToGetSpinlock()` shall be callable from
 *       Category 2 ISR level. (SRS_Os_80018, SRS_Os_80021)
 * + [ ] [SWS_Os_00655] The AUTOSAR Operating System shall provide a
 *       `ReleaseSpinlock()` function which releases an occupied spinlock. If the
 *       spinlock is not occupied an error shall be
 *       returned. (SRS_Os_80018, SRS_Os_80021)
 * + [ ] [SWS_Os_00656] `ReleaseSpinlock()` shall be callable from
 *       Task level. (SRS_Os_80018, SRS_Os_80021)
 * + [ ] [SWS_Os_00657] `ReleaseSpinlock() shall be callable from
 *       Category 2 ISR level. (SRS_Os_80018, SRS_Os_80021)
 * + [ ] [SWS_Os_00658] The AUTOSAR Operating System shall generate an error if a Task
 *       tries to occupy a spinlock that is assigned to a Task/Category 2 ISR on
 *       the same core (including itself). (SRS_Os_80018, SRS_Os_80021)
 * + [ ] [SWS_Os_00659] The AUTOSAR Operating System shall generate an error if an
 *       Category 2 ISR tries to occupy a spinlock that is assigned to a
 *       Task/Category 2 ISR on the same core. (SRS_Os_80018, SRS_Os_80021)
 * + [ ] [SWS_Os_00660] A unique order in which multiple spinlocks can be occupied by a
 *       Task/Category 2 ISR on one core should be configurable in the AUTOSAR
 *       Operating System. This might be realized by the configuration item
 *       (`OsSpinlockSuccessor` `{NEXT_SPINLOCK}`) where `NEXT_SPINLOCK` refers to the
 *       consecutive spinlock. (See `OsSpinlockSuccessor`) (SRS_Os_80018, SRS_Os_80021)
 * + [ ] [SWS_Os_00661] The AUTOSAR Operating System shall generate an error if a
 *       Task/Category 2 ISR on a core, where the same or a different Task/ISR already
 *       holds a spinlock, tries to seize another spinlock that has not been configured
 *       as a direct or indirect successor of the latest acquired spinlock (by means
 *       of the `OsSpinlockSuccessor` configuration parameter) or if no successor is
 *       configured. (SRS_Os_80018, SRS_Os_80021)
 *
 * ### API Compliances
 *
 * + [ ] GetSpinlock
 * + [ ] ReleaseSpinlock
 * + [ ] TryToGetSpinlock
 *
 * ### Configuration Compliances
 *
 * + [ ] [ECUC_Os_00258] OsSpinlock
 *   + [ ] [ECUC_Os_01038] OsSpinlockLockMethod
 *   + [ ] [ECUC_Os_01021] OsSpinlockAccessingApplication
 *   + [ ] [ECUC_Os_01022] OsSpinlockSuccessor
 *
 * @{
 */

/**
 * @} arcos_spinlock
 */

#endif /* xwos/arcos/spinlock.h */
